Day4_Mermaid：是一個人機協作的一個好工具

前言

上一篇整理完 User Story 後，我們已經知道 ProjectManagementWeb 要提供哪些功能。不過，純文字需求常會留下不同解讀。例如「後台管理員可以新增 Task Item」看起來很清楚，真正開始開發時，還是會遇到一連串問題：誰有權限新增？指派對象不是專案成員時能不能儲存？資料錯誤要回到哪一步？

這時候可以把流程畫出來。圖不會自動替我們解決需求問題，但它能讓遺漏的條件變得明顯。

Mermaid 是一套用文字描述圖表的工具。它的語法接近 Markdown，不需要拿滑鼠逐一拖曳圖形。只要寫下節點、關係與方向，支援 Mermaid 的平台就能把文字渲染成圖。GitHub 的 Markdown、Issue、Discussion 與 Pull Request 都能直接顯示 Mermaid，因此圖表可以跟文件放在一起，也能交給 Git 追蹤修改紀錄。

對人機協作來說，文字格式很方便。我可以先把需求與規則交給 AI，請它產生 Mermaid 草稿，再逐一檢查節點、箭頭與例外流程。AI 負責整理，人負責判斷內容是否符合需求。這個順序不能顛倒，因為圖畫得出來，只代表語法可以執行，不代表業務規則正確。

開始前先認識 Mermaid 程式碼區塊

Mermaid 圖通常放在 Markdown 的 fenced code block 裡。開頭使用三個反引號，並在後面加上 mermaid：

```mermaid
flowchart LR
    A[開始] --> B[完成]
```

本文每個範例都會出現兩次相同語法：

• 「範例程式碼」使用 text，讓讀者直接看到可複製的原始碼。
• 「執行結果」使用 mermaid，讓支援 Mermaid 的平台將同一段原始碼渲染成圖。

如果目前使用的 Markdown 編輯器沒有顯示圖形，可以把程式碼貼到 Mermaid Live Editor 測試。不同平台內建的 Mermaid 版本可能不同，正式發布前仍要在目標平台確認一次。

Flowchart 流程圖

說明

流程圖用節點與箭頭表示事情如何一步步進行。方框通常是處理動作，菱形表示需要判斷的條件，箭頭則代表前往下一步的方向。

flowchart TD 表示圖由上往下排列。若想改成由左往右，可以使用 flowchart LR。對初學者來說，先掌握方框、菱形及箭頭就夠了，不需要一開始便加入大量顏色與樣式。

適用情境

流程圖適合整理表單送出、權限檢查、審核流程或錯誤處理。當一項操作會因為「是／否」得到不同結果時，流程圖通常是第一個可以考慮的圖表。

下面用「新增 Task Item」示範。後台管理員送出資料後，系統先檢查內容；資料正確才會儲存，否則回到編輯畫面。

範例程式碼

flowchart TD
    start([開始]) --> input[輸入 Task Item 資料]
    input --> submit[送出表單]
    submit --> valid{資料是否正確？}
    valid -->|否| error[顯示欄位錯誤]
    error --> input
    valid -->|是| save[儲存 Task Item]
    save --> finish([完成])

執行結果

Sequence Diagram 循序圖

說明

循序圖用來描述多個角色或系統之間的互動順序。每個參與者都有一條由上往下的生命線，訊息則依發生時間排列。閱讀時從圖的上方往下看，就能知道誰先送出請求、誰負責處理，以及結果回到哪裡。

->> 可用來表示呼叫，-->> 常用於回傳結果。它們只是圖上的表達方式，不會真的發送 HTTP Request。

適用情境

循序圖適合說明登入、API 呼叫、寄送 Email 或多個服務之間的通訊。只要問題是在問「誰先呼叫誰」或「資料依序經過哪些系統」，就可以使用循序圖。

下面把登入拆成使用者、Vue 前端、ASP.NET Core API 與資料庫四個參與者。

範例程式碼

sequenceDiagram
    actor user as 使用者
    participant web as Vue 前端
    participant api as ASP.NET Core API
    participant db as SQL Server

    user->>web: 輸入帳號與密碼
    web->>api: POST /api/auth/login
    api->>db: 查詢使用者帳號
    db-->>api: 回傳帳號資料
    alt 帳號密碼正確
        api-->>web: 回傳登入成功
        web-->>user: 顯示 Task Item 清單
    else 登入失敗
        api-->>web: 回傳一般性錯誤訊息
        web-->>user: 顯示登入失敗
    end

執行結果

Class Diagram 類別圖

說明

類別圖描述系統的靜態結構，包括類別名稱、屬性、方法及類別之間的關係。它關心「系統有哪些物件，以及這些物件如何連在一起」，不負責呈現操作發生的時間順序。

類別內容寫在大括號內，+ 表示公開成員，- 表示私有成員。關聯線旁的 1 與 * 是多重性，用來表達一筆資料可以對應多少個物件。

適用情境

類別圖適合在撰寫 C# 類別前整理領域物件，也能用來討論職責是否放錯位置。例如 Project 負責保存專案資料，TaskItem 負責工作內容；兩者不應把所有使用者與權限邏輯都塞進同一個巨大類別。

下面只保留初學者需要的欄位與關係，暫時不加入 Repository、Service 或 DTO。

範例程式碼

classDiagram
    class User {
        +Guid Id
        +String DisplayName
    }

    class Project {
        +Guid Id
        +String Name
        +AddTaskItem()
    }

    class TaskItem {
        +Guid Id
        +String Title
        +String Status
        +ChangeStatus()
    }

    User "1" --> "*" Project : manages
    Project "1" *-- "*" TaskItem : contains
    User "0..1" --> "*" TaskItem : assigned to

執行結果

這裡的 *-- 是組合關係，表示 TaskItem 屬於 Project 的內容。這只是概念模型，不代表資料庫一定要使用 Cascade Delete；真正的刪除規則仍要依業務需求與資料保存政策決定。

State Diagram 狀態圖

說明

狀態圖關心一個物件目前處於什麼狀態，以及什麼事件可以讓它切換到下一個狀態。

[*] 表示起點或終點，箭頭左側是原本狀態，右側是新狀態，冒號後面則是觸發狀態改變的事件。狀態圖和流程圖看起來有點像，但關注重點不同：流程圖描述工作步驟，狀態圖描述同一個物件的生命週期。

適用情境

狀態圖適合訂單、請假單、工單與 Task Item。當系統需要限制哪些狀態可以互相轉換時，用狀態圖會比在文件中散落多條規則更容易檢查。

下面示範 Task Item 從待處理、進行中到完成的狀態。待處理或進行中的工作也可以取消，但完成與取消都視為終止狀態。

範例程式碼

stateDiagram-v2
    [*] --> 待處理
    待處理 --> 進行中 : 開始處理
    待處理 --> 已取消 : 取消工作
    進行中 --> 已完成 : 完成工作
    進行中 --> 已取消 : 取消工作
    已完成 --> [*]
    已取消 --> [*]

執行結果

ER Diagram 實體關聯圖

說明

實體關聯圖（Entity-Relationship Diagram，ERD）用來描述資料實體、欄位及彼此的關係。在關聯式資料庫中，一個實體通常會對應一張資料表，但設計時仍要依實際查詢、資料生命週期與一致性需求判斷。

關係線上的符號用來表示數量。例如 ||--o{ 可以讀成「左側一筆，對應右側零筆或多筆」。欄位後方的 PK 表示 Primary Key，FK 表示 Foreign Key，UK 表示 Unique Key。

適用情境

ER 圖適合在建立資料表前確認主鍵、外鍵與一對多關係，也能協助檢查外鍵放錯位置、關聯遺漏或多值資料被塞進單一欄位等問題。

下面用 User、Project 與 TaskItem 示範。一位使用者可以管理多個專案；一個專案可以包含多個 Task Item；Task Item 也可以先不指定負責人，因此 assignee_id 可以為空值。圖上表達的是結構，Nullability 與刪除策略仍應在 Table Schema 中明確記錄。

範例程式碼

erDiagram
    USER ||--o{ PROJECT : manages
    PROJECT ||--o{ TASK_ITEM : contains
    USER o|--o{ TASK_ITEM : assigned_to

    USER {
        uuid id PK
        string display_name
        string email UK
    }

    PROJECT {
        uuid id PK
        uuid manager_id FK
        string name
    }

    TASK_ITEM {
        uuid id PK
        uuid project_id FK
        uuid assignee_id FK
        string title
        string status
    }

執行結果

C4 Container Diagram

說明

C4 Model 用不同縮放層級描述軟體架構。Context 看系統與外界的關係，Container 看系統內可獨立執行或儲存資料的單位，Component 則繼續放大某一個 Container 的內部責任。

C4 的 Container 不等於 Docker Container。前端網站、後端 API、資料庫或行動應用程式都可以是 C4 Container，重點是它們各自有明確的技術選擇與責任。

Mermaid 官方目前仍把 C4 Diagram 標示為實驗性功能，語法與呈現方式可能隨版本調整。若預覽工具的版本較舊，這張圖也可能無法渲染。

適用情境

C4 Container Diagram 適合向開發者或維運人員說明系統由哪些應用程式、資料庫與外部服務組成，以及它們用什麼方式溝通。它不適合放入每一個 Class、DTO 或資料表，否則圖會失去架構層級的重點。

下面將 ProjectManagementWeb 拆成 Vue 前端、ASP.NET Core API 與 SQL Server，並標示外部 Email 服務。

範例程式碼

C4Container
    title ProjectManagementWeb - Container Diagram

    Person(user, "使用者", "管理專案與 Task Item")
    System_Ext(email, "Email 服務", "寄送驗證信與到期提醒")

    System_Boundary(projectManagementWeb, "ProjectManagementWeb") {
        Container(web, "Web 前端", "Vue 3", "提供操作介面")
        Container(api, "後端 API", "ASP.NET Core", "處理授權與業務規則")
        ContainerDb(database, "資料庫", "SQL Server", "保存系統資料")
    }

    Rel(user, web, "操作", "HTTPS")
    Rel(web, api, "呼叫 API", "JSON/HTTPS")
    Rel(api, database, "讀寫資料", "SQL")
    Rel(api, email, "寄送通知", "SMTP/HTTPS")

執行結果

常用圖表快速對照

Mermaid 與 AI 要怎麼分工？

請 AI 畫圖前，我會先提供角色、正常流程、錯誤流程與不能自行更動的規則。例如：

請將「新增 Task Item」整理成 Mermaid flowchart。
角色：後台管理員。
規則：指派對象必須是有效專案成員，開始時間不得晚於交付期限。
例外：權限不足、欄位錯誤與儲存失敗。
不要自行新增業務規則；不確定的內容請另外列出。

AI 產生草稿後，至少要檢查以下內容：

1. 圖上的角色與用詞是否和 User Story 一致。
2. 判斷節點是否同時處理成功與失敗結果。
3. AI 是否自行增加需求中沒有出現的欄位、權限或服務。
4. 圖表是否能在實際使用的 Markdown 平台渲染。

我把 Mermaid 當成共同編輯的設計文字。AI 可以加快第一版草稿的整理速度，需求判斷與最後審查仍由人負責。下一篇會使用 C4 Context、Container 與 Component 圖，把 ProjectManagementWeb 的系統邊界與各個元件責任說清楚。

參考資料

• Mermaid 官方文件：About Mermaid
• Mermaid 官方文件：Flowcharts
• Mermaid 官方文件：Sequence diagrams
• Mermaid 官方文件：Class diagrams
• Mermaid 官方文件：State diagrams
• Mermaid 官方文件：Entity Relationship Diagrams
• Mermaid 官方文件：C4 Diagrams
• GitHub Docs：Creating diagrams